在 Visual Studio 中設定 GitLab 作為 NuGet Packages 來源

TLDR

• GitLab Package Registry 可作為私有 NuGet 套件庫，透過 GitLab CI/CD 自動化打包與發佈流程。
• CI/CD 流程中需正確設定 dotnet nuget add source 並使用 CI_JOB_TOKEN 進行驗證。
• 若 CI/CD 流程中發生 NU1101 錯誤，需在 GitLab 的「Job token permissions」中擴充存取權限。
• Visual Studio 使用者需建立具有 read_api 權限的 Personal Access Token，並於 NuGet 套件來源中設定憑證。
• 若 Visual Studio 反覆要求輸入憑證，請檢查並手動修正 %AppData%\NuGet\NuGet.Config 中的 <packageSourceCredentials> 設定。

使用 GitLab Packages 作為套件庫

對於公司內部的公用套件，建議建立專門的 GitLab 群組來管理套件專案，並利用 GitLab Packages 作為套件來源。由於 GitLab 未提供直接上傳 .nupkg 的 UI 介面，建議透過 GitLab CI/CD 實現自動化發佈。

設定 GitLab CI/CD 自動發佈

透過 CI/CD 流程，可以自動化執行 dotnet pack 與 dotnet nuget push。以下為建議的 YAML 設定範例：

image: 'mcr.microsoft.com/dotnet/sdk:8.0'

stages:
 - pack
 - publish

variables:
 NUGET_PACKAGES_DIRECTORY: '.nuget'

before_script:
 - export PROJECT_FILE=$(find . -type f -name "*.csproj" | head -n 1)
 - export PROJECT_DIR=$(dirname "$PROJECT_FILE")
 - dotnet nuget add source "${CI_API_V4_URL}/groups/${PACKAGES_GROUP_ID}/-/packages/nuget/index.json" --name gitlab-packages --username gitlab-ci-token --password ${CI_JOB_TOKEN} --store-password-in-clear-text

pack:
 stage: pack
 script:
   - dotnet pack $PROJECT_DIR --configuration Release --output $NUGET_PACKAGES_DIRECTORY
 artifacts:
   paths:
     - $NUGET_PACKAGES_DIRECTORY/*.nupkg

publish:
 stage: publish
 script:
   - dotnet nuget add source "${CI_SERVER_URL}/api/v4/projects/${CI_PROJECT_ID}/packages/nuget/index.json" --name gitlab-project --username gitlab-ci-token --password ${CI_JOB_TOKEN} --store-password-in-clear-text
   - cd $NUGET_PACKAGES_DIRECTORY
   - for pkg in *.nupkg; do dotnet nuget push "$pkg" --source gitlab-project; done

解決 CI/CD 權限問題

什麼情況下會遇到這個問題：當 CI/CD Pipeline 在執行 dotnet restore 或 push 時，出現 error NU1101: Unable to find package 錯誤。

這是因為 $CI_JOB_TOKEN 預設僅能存取當前專案的 Packages。若要解決此問題，請執行以下步驟：

1. 前往 GitLab 專案的「Settings」→「CI/CD」。
2. 找到「Job token permissions」區塊，點擊「Add group or project」。
3. 新增需要存取的群組或專案，以擴充 Token 的權限範圍。

TIP

在未設定權限前，即使 Token 設定正確，dotnet restore 仍會因為無法解析相依套件而失敗。增加 --verbosity detailed 參數可協助確認是否為權限不足導致的 NU1101 錯誤。

在 Visual Studio 中設定 GitLab 套件來源

建立存取 Token

若要讓 Visual Studio 讀取私有套件，需建立 Personal Access Token：

1. 進入「Preferences」→「Access Tokens」。
2. 勾選 read_api 權限。
3. 產生並妥善保存 Token（僅顯示一次）。

設定 Visual Studio 憑證

在 Visual Studio 的「工具」→「選項」→「NuGet 套件管理員」→「套件來源」中加入 GitLab 的 NuGet URL。若設定後 Visual Studio 反覆跳出憑證輸入視窗，請檢查 %AppData%\NuGet\NuGet.Config 是否包含 <packageSourceCredentials> 區塊。

若設定檔遺失憑證，可透過命令提示字元手動加入：

dotnet nuget add source "https://{GitLab Domain}/api/v4/groups/{Group 流水號}/-/packages/nuget/index.json" --name=GitLab --username={GitLab 帳號} --password={Access Token}


異動歷程

• 2025-03-30 初版文件建立。